.TH "profile " 1 "" ""


.SS NAME
.P
profile \-\- Analyze the options of mpeg2enc

.SS SYNOPSIS
.P
\fBprofile\fR [ \fIOPTIONS\fR ] \fB\-f\fR \fI/path/to/video.avi\fR

.SS DESCRIPTION
.P
profile evaluates the encoding options of mpeg2enc (from mjpegtools). profile takes a video and systematically encodes it with mpeg2enc to measure various effects of mpeg2enc's options on output video bitrate, encoding time, and quality, leaving the data in a comma separated values (.csv) file.

.P
Additional command line options tell profile to take a snap shot from each test trial and to find the Peak\-Signal\-to\-Noise ratio (PSNR) between the original video file and each test trial. Further options tweak the properties of profile's behavior.

.SS FEATURES
.RS
.IP \(bu 3
Tests any and every mpeg2enc option, recording the output bitrate and encoding time (both in absolute units and normalized to an optionless 'control' trial).
.IP \(bu 3
Captures an encoded frame from each trial.
.IP \(bu 3
Finds the Peak\-Signal\-to\-Noise (PSNR) ratio between the source video and each encoded trial.
.RE

.SS OPTIONS
.SS Required Options
.TP
\fB\-f\fR, \fB\-file\fR \fI/path/to/video.avi\fR
Evaluate mpeg2enc using video.avi. Specify a full or relative path to the source video file. profile will use this video to test the mpeg2enc options you specify (see \fB\-t\fR).

.SS Logs
.TP
\fB\-l\fR, \fB\-logfile\fR \fI/path/to/logfile.csv\fR
Specify a different path for the data file other than the default: $HOME/.vidprofile/profile.csv. The data file is saved as a plain ASCII comma\-separated values file (.csv) for further analysis and plotting.

Recorded data: the tested mpeg2enc command line option(s), duration of source video (s), time to encode (s), output size (kB), time scale factor, output bitrate (kbps), normalized time (%), normalized bitrate (%), and the averaged Peak\-Signal\-to\-Noise Ratio (dB).

.TP
\fB\-el\fR, \fB\-errlog\fR \fI/path/to/error.log\fR
Specify a different path for the error log other than the default: /dev/null. All subprocess errors are written here EXCEPT for mplayer's and mpeg2enc's errors, which are written to \fB\-enclog\fR.

.TP
\fB\-nl\fR, \fB\-enclog\fR \fI/path/to/encoder.log\fR
Specify a different path for the encoding log other than the default: /dev/null. This log is incredibly verbose: all of mplayer's and mpeg2enc's frame\-by\-frame statistics (and errors, if any) are written here.

.TP
\fB\-pl\fR, \fB\-psnrlog\fR \fI/path/to/psnr.csv\fR
Specify a different path for the frame\-by\-frame Peak\-Signal\-to\-Noise Ratio data other than the default: $HOME/.vidprofile/psnr.csv. The data file is saved as a plain ASCII comma\-separated values file (.csv) for further analysis and plotting.

Recorded data: frame number, Y (or luminance) PSNR (dB), Cb (or blue chroma) PSNR (dB), Cr (or red chroma) PSNR (dB),  whole frame PSNR (dB), frame PSNR error, cumulative error sum.

In cases where the images do not differ, the PSNR cannot be found (because the denominator is zero). Since the images are exactly the same, there is no 'noise', and the PSNR is infinite instead.

NOTE: nothing will be written to the log unless the PSNR is calculated (see \fB\-p\fR).

.SS Option Tests
.P
The main purpose of profile is to test mpeg2enc's many options on a video to evaluate the encoder's behavior.

.P
mpeg2enc has many different options which separate into three classes. Some are flags (either on or off), others independently take one numerical argument in a valid range, and finally some are inter\-dependent, where using one implies using another. The classic example of inter\-dependent options in mpeg2enc is \-b and \-q. Using \-q (quantization) implies a variable bitrate, and thus to keep the bitrate under control, \-b can be used to limit the maximum bitrate.

.P
profile can test EVERY option of mpeg2enc; the following (summarized) mpeg2enc options are the more interesting ones. See the mpeg2enc man page for complete details of these (and the other) options.

.P
There are two generalized test specifications:

.TP
\fB\-t\fR, \fB\-test\fR \fB"\fR\fITEST\fR\fB"\fR
Multiple tests (\-t) may be called for any profile (see the EXAMPLES).

.TP
\fB\-t\fR, \fB\-test\fR \fB"\fR\fITEST 1\fR\fB:\fR\fITEST 2\fR\fB:\fR\fITEST 3\fR\fB"\fR
Instead of specifying each test with a separate \-t option, you may specify many tests at once using a colon (\fB:\fR) as a separator.

.P
Tests are carried out in the order specified (so no reshuffling). In addition, if tests are specified in the default (or in a \fB\-c\fR given) configuration file, the tests given on command line DO NOT override the configuration file tests. Instead, the command line tests are appended to the end of the test list and carried out last. You may have overlapping tests if you're not careful! This is not a Bad Thing, but you'll run the same test more than once and waste some time.

.P
Each encoder option class has its own syntax as described below:

.SS Suggested flags
.TP
\fB"\-\fR\fIFLAG\fR\fB"\fR
A \fIFLAG\fR in mpeg2enc takes no numerical arguments: it simply turns on a feature, like a switch. Consequently, only the flag must be given.

.P
A \fIFLAG\fR is called using the same letter as those for mpeg2enc:

.TP
\fBc\fR
Generate closed GOPs.

.TP
\fBH\fR
Keep the high\-frequency information.

.TP
\fBp\fR
Tell the _decoder_ to use 3\-2 pulldown.

.TP
\fBs\fR
Generate sequence headers for ff/rew/seek.

.SS Suggested independent numerical options
.TP
\fB"\-\fR\fIOPTION MIN MAX STEP\fR\fB"\fR
An independent numerical option needs four pieces of information to completely specify an option test: the option to test (\fIOPTION\fR), the value at which to start testing (\fIMIN\fR), the value at which to finish testing (\fIMAX\fR), and the numerical increment between tests (\fISTEP\fR). 

NOTE: if an option can take a decimal argument, both \fIMAX\fR and \fISTEP\fR must have the \fBsame\fR number of decimal places.

.P
Each \fIOPTION\fR is called using the same letter as those for mpeg2enc:

.TP
\fBD\fR  9..10
DC component precision.

.TP
\fBE\fR  \-40..40
The 'unit coefficient elimination' threshold.

.TP
\fBN\fR  0.0..2.0
Reduce high\-frequency content. 0.0 means don't reduce.

.TP
\fBr\fR  8|16|24|32
Motion search radius.

.TP
\fBR\fR  0..2
Number of B\-frames between I\- or P\-frames.

.SS Suggested inter-dependent numerical options
.TP
\fB"\-\fR\fIOPTION1 MIN1 MAX1 STEP1\fR \fB\-\fR\fIOPTION2 MIN2 MAX2 STEP2\fR\fB"\fR
Inter\-dependent numerical options are similar to independent numerical options, but using one inter\-dependent option implies the use of another option (or creates the need to use another option). Specifying inter\-dependent options is just giving two options with ranges. 

Eight pieces of information are needed: the first option to test (\fIOPTION1\fR), that option's value at which to start testing (\fIMIN1\fR), that option's value at which to finish testing (\fIMAX1\fR), and that option's numerical increment between tests (\fISTEP1\fR). 

Next, the second option to test (\fIOPTION2\fR), that option's value at which to start testing (\fIMIN2\fR), that option's value at which to finish testing (\fIMAX2\fR), and that option's numerical increment between tests (\fISTEP2\fR). 

NOTE: if an option can take a decimal argument, both \fIMAX\fR and \fISTEP\fR must have the \fBsame\fR number of decimal points.

.P
profile makes no strictly defined distinction between an independent option and an inter\-dependent option. In fact, profile uses the length of the test string to determine which test to run. Consequently, there's no reason you cannot specify 'independent' options as 'inter\-dependent' options. For example, \fB\-t "\-E \-40 40 5 \-Q 0.0 5.0 1.0"\fR, which will evaluate the inter\-dependence of \-E and \-Q, is a perfectly valid test specification.

.P
Each OPTION is called using the same number/letter as those for mpeg2enc:

.TP
\fB2\fR  1..4
.TP
\fB4\fR  1..4
Motion estimation aggressiveness. \-4 controls 4*4 pixel areas, and \-2 controls 2*2 pixel areas.

.TP
\fBb\fR  100..15000
The video bitrate. When \-q is present, variable bitrate encoding is enabled, and \-b becomes the maximum bitrate.
.TP
\fBq\fR  1..31
Amount of quantization. A lower number implies less quantization and thus higher quality.

.TP
\fBg\fR  1..24
.TP
\fBG\fR  1..24
Limits for the size of GOPs (Group of Pictures). \-g is the lower limit; \-G is the upper limit.

.TP
\fBQ\fR  0.0..5.0
Reduce the quantization for highly detailed blocks as needed. 0.0 means always use the same quantization for the entire frame.
.TP
\fBX\fR  0.0..2500.0
Luma (brightness) variance below which to use \-Q.

.SS Other Options
.TP
\fB\-c\fR, \fB\-config\fR \fI/path/to/config.file\fR
Specify a path to a config file; profile looks for a default configuration file in $HOME/.vidprofile/profile.conf and reads it before starting. See FILES (or the README) for an example configuration file. When using a configuration file, all command line options placed _after_ the configuration file will override the options in the configuration file (except for \fB\-t\fR, in which case all tests are included and none are overridden). If the default configuration file exists and another file is specified with \-c, the specified file takes precedence over the default file. The order of importance, from least to most important, is: default configuration file, specified configuration file, right\-most command line options.

.TP
\fB\-k\fR, \fB\-keepvids\fR
Keep encoded videos. After each option trial is finished, profile deletes the encoded video by default. Use this option if you want to keep every trial encoding. Videos are left in the present working directory, so this could take up a lot of space!

.TP
\fB\-nf\fR, \fB\-encframe\fR \fINUMBER\fR
Encode \fINUMBER\fR frames. profile encodes the _entire_ source video for every trial by default. If you don't want to encode the whole file, you may specify an integer number of frames (\fINUMBER\fR) to encode with this option. As a rule of thumb, 1 second of NTSC video is 30 frames and one second of PAL video is 25 frames.

.TP
\fB\-p\fR, \fB\-psnr\fR \fINUMBER\fR|\fBall\fR
Find the Peak\-Signal\-to\-Noise Ratio for \fINUMBER\fR frames. profile does not find the Peak\-Signal\-to\-Noise Ratio by default. If you want to find the PSNR between the source video and each encoded trial, use this option. \fINUMBER\fR is the number of frames to average for the PSNR (use \fBall\fR to compare the entire videos). If \fB\-nf\fR is given, the number of PSNR frames must be less than or equal to the number of encoded frames.

.TP
\fB\-s\fR, \fB\-snapshot\fR \fINUMBER\fR
Take a snapshot of frame \fINUMBER\fR. profile can take one frame from the source video and each encoded trial. Use this option to enable this feature and specify which frame to capture. Like \-p, if \fB\-nf\fR is specified, the snapshot frame number must be less than or equal to the number of encoded frames. Snapshots are left in the present working directory.

.TP
\fB\-h\fR, \fB\-help\fR
Display a usage guide and exit.

.TP
\fB\-v\fR, \fB\-version\fR
Print the version number and exit.

.SS EXAMPLES
.TP
profile \-t "\-H" \-t "\-4 1 4 1 \-2 1 4 1" \-nf 450 \-f /home/foo/bar.avi
Test the flag \-H, and the options \-4 and \-2 using the first 450 frames from /home/foo/bar.avi. First, \-H will be tested. Next, \-2 will be tested for 1, 2, 3, and 4 while \-4 is at 1; then, \-4 will be set to 2 and \-2 will be tested from 1 to 4 again; and so on until \-4 reaches 4. Provided the default config file isn't present, or sets the other options, logs are sent to the default locations, snapshots are not taken, encoded videos are not kept, and the PSNR is not calculated.

.TP
profile \-c $HOME/.vidprofile/custom.conf \-l $HOME/profile\-data.csv
Test all the flags present in $HOME/.vidprofile/custom.conf, and use other settings specified (like snapshots or PSNR) in that file. Specifying \-l after \-c ensures the data log will be written to $HOME/profile\-data.csv (even if \-c lists a custom data log location \- options to the right of \-c override any options in the config file).

.SS FILES
.TP
$HOME/.vidprofile/profile.csv
The data output file. See \fB\-l\fR for more description.

.TP
$HOME/.vidprofile/profile.conf
The default configuration file. See \fB\-c\fR for more description on its use.

.P
Sample configuration file:

.nf
  profile
  # Config file for profile. DO NOT COMMENT IN-LINE
  #
  # Options given before -c/-config on the command line will 
  # be overridden by this config file.
  
  ########
  # Logs #
  ########
  
  # logfile (default: $HOME/.vidprofile/profile.csv)
  # Where should the main data be written?
  #-logfile $HOME/.vidprofile/profile.csv
  
  # errlog (default: /dev/null)
  # Where should errors be sent?
  #-errlog $HOME/.vidprofile/profile.err
  
  # enclog (default: /dev/null)
  # Where should mplayer's and mpeg2enc's output be sent?
  #-enclog /dev/null
  
  # psnrlog (default: $HOME/.vidprofile/psnr.csv)
  # Where should the frame-by-frame PSNR report be sent?
  #-psnrlog $HOME/.vidprofile/psnr.csv
  
  ################
  # Tests to run #
  ################
  
  # Which options of mpeg2enc should be tested?
  # See 'man mpeg2enc' for further option explanations.
  # Uncomment a test to run that test.
  
  # Flags
  #-test "-p"
  #-test "-H"
  #-test "-s"
  #-test "-c"
  
  # Single ranges
  # The syntax is:
  # [option] [min] [max] [step]
  # [step] may be a decimal as long as [max] has the same 
  #   number of decimal points.
  #     eg "-N 0 2.0 0.4" is OK, while
  #        "-N 0 2   0.4" is not.
  #-test "-R 0 2 1"
  #-test "-E -40 40 5"
  #-test "-r 8 32 8"
  #-test "-D 9 10 1"
  #-test "-N 0.0 2.0 0.4"
  
  # Double ranges
  # The syntax is:
  # [option1] [min1] [max1] [step1] [min2] [max2] [step2]
  # [step1|2] may be a decimal as long as [max1|2] has the 
  #   same number of decimal points.
  # The second option range is tested fully for each case 
  #   of the first option.
  #     eg "-b 800 9800 500 -q 1 18 1" means run 
  #     -q 1 18 1 for -b 800, then increment -b, repeat
  #-test "-b 800 9800 500 -q 1 18 1"
  #-test "-4 1 4 1 -2 1 4 1"
  #-test "-Q 0 5 1 -X 0 1000 100"
  #-test "-G 2 24 2 -g 2 24 2"
  
  #################
  # Other options #
  #################
  
  # encframes (default: the whole movie)
  # How many frames should mplayer send to mpeg2enc?
  # To encode the entire input file, comment this line, 
  #   or set the the number of frames to more than the 
  #   frames in the input file.
  # 450 frames play just longer than 15sec (NTSC) or 18sec (PAL)
  #-encframe 450
  
  # keepvids
  # Keep the videos mpeg2enc creates?
  # The script leaves the movies in the same directory from 
  #   which it was called.
  #-keepvids
  
  # snapshot
  # Take a frame from each test?
  # If so, which one? (must be less than either the number of 
  #   frames mplayer sends to mpeg2enc, above, or the amount of 
  #   frames in the entire input file) The script leaves the snap 
  #   shots in the same directory from which it was called.
  #-snapshot 50
  
  # psnr
  # Find the Peak Signal to Noise Ratio?
  # If so, how many frames should be compared? (must be less 
  #   than either the number of frames mplayer sends to mpeg2enc, 
  #   above, or the amount of frames in the entire input file)
  # Comment for every frame of the encoded videos. 
  # NOTE: each frame is about 1MB, please have sufficient space in the
  #   present working directory.
  #-psnr 60
.fi


.SS SEE ALSO
.P
\fBpsnrcore\fR(1), \fBvidpsnr\fR(1)

.SS BUGS
.P
It is possible to pass options to mpeg2enc that aren't options. When checking for a test's validity, only the number of arguments in a test are counted. Thus, if a test is specified that matches a correct length (1, 4, or 8 fields), it will be passed to mpeg2enc, which may break things. eg \-Z is not an option, but calling \-t "\-Z 1 10 2" would pass the input checks and break profile.

.P
On a similar note: Whether or not an option takes a numerical argument is not checked: eg \-t "\-H 0 5 1" would break profile (\-H is a flag!). Also, whether or not a test has numerical values isn't checked: eg \-t "\-E foo bar stop" would break profile.

.P
If an option can take a decimal argument, both MAX and STEP must have the same number of decimal points: eg \-t "\-N 0 2 0.1" would break profile (needs to be \-t "\-N 0.0 2\fB.0\fR 0.1").

.SS AUTHOR
.P
Streamlined and made robust by Joe Friedrichsen. Original idea and rough\-cut by Eric Pierce.

.SS CONTACT
.P
Send bugs to vidprofile\-users@lists.berlios.de. Please see the vidprofile homepage (http://vidprofile.berlios.de) for further information.


.\" man code generated by txt2tags 2.3 (http://txt2tags.sf.net)
.\" cmdline: txt2tags -t man --infile=src/profile.t2t --outfile=./profile.man

